//+------------------------------------------------------------------+
//|                                                        Label.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "WndObj.h"                                  // 窗口对象基类（提供基础控件能力）
#include <ChartObjects/ChartObjectsTxtControls.h>     // 图表文本控件类（包含 CChartObjectLabel）

//+------------------------------------------------------------------+
//| CLabel 类：MQL5 标签控件类                                       |
//| 核心能力：封装图表对象 CChartObjectLabel，提供静态文本显示功能，   |
//|           支持文本内容、颜色、字体和大小的配置                     |
//| 适用场景：静态文本说明、标题、状态提示等无需用户交互的文本展示     |
//+------------------------------------------------------------------+
class CLabel : public CWndObj
  {
private:
   CChartObjectLabel m_label;               // 图表标签对象（底层实现，负责在图表上绘制文本）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化标签默认状态
    * @details 初始化标签文本颜色为系统默认标签颜色（CONTROLS_LABEL_COLOR）
    */
                     CLabel(void);

   /**
    * @brief 析构函数：清理标签资源
    * @details 依赖父类 CWndObj 的析构逻辑，自动释放底层图表对象 m_label
    */
                    ~CLabel(void);

   //----------------------------------------------------------------
   // 控件创建：在图表上创建标签
   //----------------------------------------------------------------
   /**
    * @brief 在指定图表位置创建标签控件
    * @param chart [in] 目标图表ID（0 表示当前活跃图表）
    * @param name [in] 控件唯一标识名（图表内不可重复）
    * @param subwin [in] 绑定的子窗口编号（0 = 主窗口，≥1 = 指标子窗口）
    * @param x1 [in] 左上角X坐标（像素，相对于图表窗口）
    * @param y1 [in] 左上角Y坐标（像素）
    * @param x2 [in] 右下角X坐标（像素，通常不影响标签显示，仅用于布局计算）
    * @param y2 [in] 右下角Y坐标（像素，同上）
    * @return bool - 创建结果：true=成功（父类初始化+底层对象创建完成），false=失败
    */
   virtual bool      Create(const long chart,const string name,const int subwin,const int x1,const int y1,const int x2,const int y2);

protected:
   //----------------------------------------------------------------
   // 控件属性更新处理器（保护，仅子类可重写）
   //----------------------------------------------------------------
   /**
    * @brief 文本更新处理器（文本变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_label 的描述文本），false=失败
    */
   virtual bool      OnSetText(void);

   /**
    * @brief 文本颜色更新处理器（颜色变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_label 的文本颜色），false=失败
    */
   virtual bool      OnSetColor(void);

   /**
    * @brief 字体更新处理器（字体变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_label 的字体），false=失败
    */
   virtual bool      OnSetFont(void);

   /**
    * @brief 字体大小更新处理器（大小变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_label 的字体大小），false=失败
    */
   virtual bool      OnSetFontSize(void);

   //----------------------------------------------------------------
   // 控件生命周期事件处理器（保护，仅子类可重写）
   //----------------------------------------------------------------
   /**
    * @brief 创建完成事件回调（控件创建后触发）
    * @return bool - 处理结果：true=成功（底层对象初始化完成），false=失败
    */
   virtual bool      OnCreate(void);

   /**
    * @brief 显示事件回调（控件从隐藏变为显示时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧显示），false=失败
    */
   virtual bool      OnShow(void);

   /**
    * @brief 隐藏事件回调（控件从显示变为隐藏时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧隐藏），false=失败
    */
   virtual bool      OnHide(void);

   /**
    * @brief 移动事件回调（控件位置变化时触发）
    * @return bool - 处理结果：true=成功（更新底层对象位置），false=失败
    */
   virtual bool      OnMove(void);
  };
//+------------------------------------------------------------------+